Skip to content

fix(planner): give MetricsQL roots the series identity - #1339

Merged
zzylol merged 3 commits into
mainfrom
fix/metricsql-series-identity
Nov 16, 2026
Merged

zzylol merged 3 commits into
mainfrom
fix/metricsql-series-identity

Conversation

@zzylol

@zzylol zzylol commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Problem: a MetricsQL workload never got the series-identity column, so sum by (job)(rate(requests_total[5m])), increase(requests_total[5m]), max_over_time(latency[5m]) and sum(latency{job="j1"}) (1,000 series at 1 Hz, every 10 s, relative error 0.01) had no installable plan, while the same text as PromQL plans.
  • Change: one rule, QueryLanguage::reads_time_series() (PromQL and MetricsQL), decides which roots get the identity in Stage1ToStage3Pass::optimize.
  • Effect: all four MetricsQL queries plan, install, select the PromQL form's DAG node for node, and give the same answers on synthetic data. Queries that did plan before, such as avg by (job)(latency), no longer give wrong answers without any error (j1 14 → 9 on the test's samples).

Closes #1337.

Review guide

Base: main (6b4847c9a). Head: 562e50b00. Three commits:
the regression tests first (they fail on main), then the fix, then the round-1 review fixes (rename, shared test helpers, the wrong-answer test).

  • Read first: crates/types/src/workload/query.rs (QueryLanguage::reads_time_series) and crates/planner/src/run.rs (Stage1ToStage3Pass::optimize), about 15 changed lines.
  • New tests: crates/planner/tests/metricsql_workloads.rs.
  • Mechanical: the test helpers Answer, answers, sample, query_roots, run(dag, store, ids, scope) and assert_answers_near move from runtime_install.rs to the shared crates/planner/tests/time_series/mod.rs, plus a new assert_answers_near_relative. Both test files use the one copy. runtime_install.rs's CountingStore / RAW_DATA_READS read counter is deleted: it was written but no test read it.

Other places checked for a PromQL-only gate:

Place Decides by Change
Stage1ToStage3Pass::optimize (crates/planner/src/run.rs) language == PromQL now language.reads_time_series()
frontend resolver promql_series (crates/frontend-common/src/resolve.rs) the child's schema (closed), shared by both frontends none
executor (has_promql_series_identity on schemas) the schema none
devtools lower_promql_roots (crates/devtools/src/planning_stages.rs) lowers PromQL only, always adds the identity none
devtools asap_planner CLI lowered, lowered_together PromQL or else SQL lowering; devtools has no MetricsQL frontend none (#1340)

Rebase onto main 6b4847c9a

Rebased from 3e434c760 onto main at 6b4847c9a, after the merge of #1242. The 3 commits stay; the previous head 04d6a9214 is kept as backup/fix/metricsql-series-identity-04d6a9214. #1242 had already moved sample and run(dag, store, ids, scope) into crates/planner/tests/time_series/mod.rs. Conflicts:

File Conflict Resolution
crates/planner/tests/main.rs main's mod reduce_aggregates; and this PR's mod metricsql_workloads; both
crates/planner/src/run.rs main's promql_root(node, with_promql_series_identity(node))? (a realization defect is an error) and this PR's match series_identity main's promql_root inside this PR's reads_time_series match; its doc now says "PromQL or MetricsQL root"
crates/planner/tests/time_series/mod.rs main's labels() and sample() and main's run at the top; this PR's sample() and run after query_roots main's labels() and sample() (main's reduce_aggregates.rs uses them); this PR's one run
crates/planner/tests/runtime_install.rs main's CountingStore wrappers at both run calls this PR's side: CountingStore / RAW_DATA_READS is deleted (nothing reads the count), and the calls pass time_series_tables(...)

Checked on the rebased head 562e50b00, by test name against main 6b4847c9a: cargo check --workspace --all-targets, cargo fmt --all -- --check and cargo clippy -p asap-planner -p asap-types --all-targets -- -D warnings are clean. cargo test -p asap-planner -p asap-types: 319 passed, 1 failed, 1 ignored. The 1 (summary_sharing::identical_ungrouped_queries_share_their_producers) fails on main too. All 4 metricsql_workloads tests pass.

Rebase onto main 3e434c760

Rebased from 59365ce80 onto main at 3e434c760, after the merge of the Stage 3 execution-contexts refactor (#1237). Same 3 commits. Conflicts:

  • crates/planner/tests/main.rs: both mod exact_only_reads; and mod metricsql_workloads;.
  • crates/planner/tests/runtime_install.rs imports: kept main's use asap_types::ir::{ASAPOp, NonASAPOp, Operator}; (its new one_chain_serves_two_evaluation_contexts test reads them) and dropped Source, which only the helpers this PR moved to time_series read.

Checked on the rebased head, by test name against main 3e434c760: cargo check --workspace --all-targets, cargo fmt --all -- --check and cargo clippy -p asap-planner -p asap-types --all-targets -- -D warnings are clean. cargo test -p asap-planner -p asap-types: 285 passed, 2 failed, 1 ignored. The 2 (runtime_install::check_compiles_reports_the_executors_error, summary_sharing::identical_ungrouped_queries_share_their_producers) fail on main too. All 4 metricsql_workloads tests pass.

Behavior: before → after

The workload (MetricsQL):

{"query_workload": {"language": "metricsql", "repeating_queries": [{
   "query": "sum by (job)(rate(requests_total[5m]))",
   "demand": {"fixed_interval_at": {"interval": 10000, "evaluation_phase": 0}},
   "requirements": {"accuracy": {"max_error": 0.01}},
   "predictability": {"predictable": {"known_at": null}}}]},
 "data_workload": {"arrival": {"ingesting": {"rows_per_second": 2000.0}},
   "sources": {
     "requests_total": {"series_count": 1000, "metric_type": "counter", "sample_interval": 1000},
     "latency": {"series_count": 1000, "metric_type": "gauge", "sample_interval": 1000}}}}

planned with plan_installable(UserInput::new(&workload, FrontendInput::Metricsql, PlanningModels::builtin())):

Query Before After
sum by (job)(rate(requests_total[5m])) installable plan: the executor cannot compile the plan's query run: invalid DAG: per-entity summary requires complete source identity plans; DAG equals the PromQL form's
increase(requests_total[5m]) same error plans; answers a 20, b 40, c 60, d 80 (= PromQL)
max_over_time(latency[5m]) same error plans; answers a 6, b 16, c 26, d 36 (= PromQL)
sum(latency{job="j1"}) ... invalid DAG: node 2: invalid DAG: native output type differs from Planner output plans; answers 18 (= PromQL)
avg by (job)(latency) plans and runs with no error, but answers j1 14, j2 34 (wrong) answers j1 9, j2 29 (= PromQL)

The last row is the dangerous case: without the identity, MetricsQL rows of different series under one job are not told apart, so the average is wrong and nothing reports an error. (A review run on other synthetic data saw j1 14.05 where 9.05 is correct.)

This serves correctness: a workload's language must not change whether it plans when both languages lower to the same time-series IR.

Interfaces

crates/types/src/workload/query.rs

+impl QueryLanguage {
+    /// Whether this language's queries read time series rather than
+    /// tables. PromQL and MetricsQL read time series:
+    /// `rate(requests_total[5m])` reads each `requests_total` series, such
+    /// as `{instance="a", job="j1"}`. SQL, DataFusion and ElasticDSL read
+    /// tables.
+    pub fn reads_time_series(&self) -> bool;
+}

Usage (the flow crates/planner/tests/metricsql_workloads.rs runs at the linked commit; its helpers workload, plan_promql, samples and query_answers are defined there):

// The workload above, written in MetricsQL: what the user submits.
let workload = workload("metricsql", "increase(requests_total[5m])");
// The one Planner call. Inside it, `Stage1ToStage3Pass::optimize` reads
// `workload.query_workload().language.reads_time_series()` (true for
// MetricsQL) and adds the `$promql_series_identity` column to each root
// before Stage 0, as it does for PromQL.
let (plan, _report) = plan_installable(UserInput::new(
    &workload,
    FrontendInput::Metricsql,
    PlanningModels::builtin(),
))
.await?;
// The selected DAG is the PromQL form's, node for node.
assert_eq!(plan.dag, plan_promql("increase(requests_total[5m])").await.dag);
// Executed at T over four series sampled every 15 s, it answers
// a 20, b 40, c 60, d 80, as the PromQL plan does.
let answered = query_answers(&plan, &samples());

Algorithm changes

None. The series-identity realization (with_promql_series_identity) is unchanged; only which languages reach it changes.

Design scope

  • QueryLanguage::reads_time_series (method, no new type or file). Scope: workload description (asap_types::workload), read by the planner facade before Stage 0. It states a property of the query language (time series vs tables), so it sits on QueryLanguage, the type whose data it reads; what the planner does with it (the identity column) is explained at the call site in run.rs. A future time-series language opts in here instead of at each call site.
  • Test helpers in crates/planner/tests/time_series/mod.rs (functions only, no new types): sample, query_roots, run, assert_answers_near, assert_answers_near_relative. Scope: the planner tests' stand-in runtime (bind raw samples, run a plan, compare answer rows), shared by every planner test that executes a plan.
  • crates/planner/tests/metricsql_workloads.rs (new test file). Scope: planner end-to-end tests by input language, next to sql_table_scans.rs; it covers MetricsQL workloads in general, not one query.

Decisions and open questions

Needs reviewer decision: None.

Decided:

  • 2026-11-15: the rule is a method on QueryLanguage rather than a matches! at the call site, so every caller uses one definition. The identity column keeps its PROMQL_SERIES_IDENTITY / with_promql_series_identity names; renaming them is out of scope.
  • 2026-11-15 (review A2): keep the explicit language gate rather than relying on the scan kind. with_promql_series_identity only changes Source::TimeSeries scans, so calling it on every root would also work today. The gate is kept because it states the rule where it is decided (the language reads time series), so it does not depend on no table frontend ever emitting a time-series scan. Rejected: dropping the gate and the method.
  • 2026-11-15 (review L1): the method is named reads_time_series (what the language is), not has_series_identity (what the planner does with it).

Verification

Commands (dedicated CARGO_TARGET_DIR): cargo test -p asap-planner, cargo test -p asap-types --lib workload::, cargo test -p asap-frontend-metricsql, cargo clippy -p asap-types -p asap-planner -p asap-frontend-metricsql --all-targets -- -D warnings, cargo fmt --all -- --check.

Scope Result Newly failing vs main Notes
asap-planner --test planner metricsql_workloads:: on main (tests only) 0 passed / 4 failed — the four errors in the table above; metricsql_grouped_average_averages_every_series_of_each_group fails with [j1 14, j2 34] vs [j1 9, j2 29]
asap-planner --test planner metricsql_workloads:: with the fix 4 passed —
asap-planner --test planner (all) 23 passed / 2 failed / 1 ignored none summary_sharing::identical_ungrouped_queries_share_their_producers and runtime_install::check_compiles_reports_the_executors_error fail identically on main
asap-planner --lib 12 passed none
asap-frontend-metricsql 15 passed none
asap-types --lib workload:: 24 passed none includes the new unit test
cargo fmt --all -- --check clean
cargo clippy ... --all-targets -D warnings clean

New tests and what each catches:

  • metricsql_queries_plan_and_install: each of the four MetricsQL queries plans and its plan compiles in the executor; catches a MetricsQL root planned without the series identity (all four fail on main).
  • metricsql_queries_select_the_promql_plan: each MetricsQL query's selected DAG equals its PromQL form's; catches any language-dependent difference left between the two frontends' roots before Stage 0.
  • metricsql_queries_answer_as_promql_does: each MetricsQL plan's answers on synthetic samples equal the PromQL plan's and the hand-worked values (increase: 20/40/60/80, max_over_time: 6/16/26/36, sum: 18); catches a plan that installs but computes something else.
  • metricsql_grouped_average_averages_every_series_of_each_group: MetricsQL avg by (job)(latency) answers j1 9, j2 29, as PromQL does; catches the case where the query plans and runs without error but answers wrong (14 and 34 on main).
  • only_promql_and_metricsql_read_time_series (asap-types): the rule is true for PromQL and MetricsQL and false for SQL, DataFusion and ElasticDSL.

Review status

Round 1 (two reviews at 79f5c74df: abstraction/layering and functional/efficiency). Both approved with small changes; no blockers. All findings are addressed in b2da40df2:

Finding Resolution
A1: run-and-compare test helpers duplicated sample, query_roots, run, assert_answers_near (+ assert_answers_near_relative) moved to time_series/mod.rs; copies deleted
A2: language gate repeats the scan kind kept the gate; see Decided
L1: name describes the planner, not the language renamed to reads_time_series; identity explanation moved to run.rs
L2: interface diff did not match the code copied from the code above
L3: devtools CLI gap had no issue #1340
L4: test read all DAG roots uses query_roots
F1: wrong answers with no error not in the table or tests new row and new test (avg by (job)(latency))
F2: two problems that also exist on main #1341 (rate[5m] / rate[10m] execution error), #1342 (MetricsQL and/or/unless)

The functional review's 59-query harness found MetricsQL equal to PromQL (same DAG, same answers) on every query whose PromQL form plans, and planning time within noise (1452.7 ms vs 1449.6 ms over 38 queries).

Follow-ups

@zzylol zzylol added bug Something isn't working ir Pre-ASAP or post-ASAP intermediate representation promql PromQL front-end lowering (L1→L2) schema Schema, type, key, and nullability contracts labels Nov 15, 2026
@zzylol
zzylol force-pushed the fix/metricsql-series-identity branch from b2da40d to 04d6a92 Compare November 16, 2026 01:45
…as PromQL

Four queries over 1,000 series at 1 Hz, every 10 s within relative error
0.01, written in both languages: each MetricsQL query plans and installs,
selects the PromQL form's DAG, and answers what the PromQL form answers on
synthetic samples (and the hand-worked answers). They fail on main:
MetricsQL roots never get the series identity.

The answer-row helper moves to the shared time_series test module.
Stage1ToStage3Pass added the series-identity column only to PromQL roots,
so MetricsQL per-series queries had no installable plan. One rule now
decides which languages carry it: QueryLanguage::has_series_identity
(PromQL and MetricsQL).

Closes #1337
…time_series

- QueryLanguage::has_series_identity becomes reads_time_series: the
  language reads time series (PromQL, MetricsQL) or tables (SQL,
  DataFusion, ElasticDSL). The identity-column explanation moves to its
  one call site in Stage1ToStage3Pass::optimize.
- The planner tests' time_series module now holds sample, query_roots,
  run(dag, store, ids, scope) and assert_answers_near (absolute) /
  assert_answers_near_relative; runtime_install and metricsql_workloads
  use them and drop their copies. The write-only read counter
  (CountingStore, RAW_DATA_READS) that no test read is deleted.
- New test: MetricsQL avg by (job)(latency) answers j1 9, j2 29 as
  PromQL does. Without the identity it planned and ran without error but
  answered 14 and 34.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working ir Pre-ASAP or post-ASAP intermediate representation promql PromQL front-end lowering (L1→L2) schema Schema, type, key, and nullability contracts

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MetricsQL roots never get the series identity, so per-series MetricsQL queries have no installable plan

1 participant